docs: align docs with current architecture; archive completed reviews - #49
Conversation
Documentation drifted vs the code in several places. This sweep brings the living docs back in sync and archives one-shot review docs whose action items have all shipped. Updated in place: - BACKLOG.md: move audition samples from "In Progress" to "Shipped" (landed in #45, #46) and link the merged backend/frontend modules. - docs/SAMPLE_GENERATION.md: header changes "Status: Prototype on branch X" -> "Status: Shipped". - apps/ui/README.md: drop "Google Gen AI SDK" from the Tech Stack — @google/genai was removed from package.json; Gemini is fully backend-mediated. - apps/backend/ARCHITECTURE.md: expand the Components table to cover csv_export.py, dsp_utils.py, dsp_bandbank.py, sample_*.py, server_samples.py, stage_status.py, symbolic_extract.py, url_ingest.py, phase1_evaluation.py, phase1_report_html.py, utils/cleanup.py. Add the missing routes: /interrupt, /samples (POST + GET). - apps/backend/README.md: extend the canonical-routes list with DELETE /runs, /interrupt, /source-audio, /export/csv, /spectral-enhancements, /pitch-note-translations, /interpretations, /samples. - apps/backend/AGENTS.md: refresh the File Map with the same new modules, add an Operator/Research Scripts section covering scripts/, and bump the stale 2026-03-10 date stamp. - apps/ui/AGENTS.md: expand the File Map with analysisRunsClient, phase2Validator, mixDoctor, spectralArtifactsClient, sampleGenerationClient, fieldAnalytics, midi/, sessionMusician/, and the types/ barrel. Note that the UI does not import an AI SDK. - CLAUDE.md: extend the backend "Core files" list with the same new modules; explicitly call out the audition-samples surface. Archived (moved to docs/history/): - docs/external-repo-review-2026-05-13.md — completed review; Tracks 1, 2, 3 all shipped or deferred. Outcomes summarized in an archive-note header. - docs/track1-spike-outcome-2026-05-13.md — completed loudness verification spike; fix landed and regression test is live. Cross-references updated: - docs/adr/0001-phase1-json-schema-v1.md - apps/backend/csv_export.py (module docstring) - apps/backend/tests/test_loudness_r128.py (module docstring) - docs/history/README.md index - relative links inside the two archived docs https://claude.ai/code/session_01YNsCxdcxQiTieUNvAgKMd9
slittycode
left a comment
slittycode
left a comment
There was a problem hiding this comment.
Verdict: APPROVE
Summary
Docs-only sweep: aligns CLAUDE.md, ARCHITECTURE.md, AGENTS.md, and README.md with the modules that shipped in #45/#46, archives two completed review docs to docs/history/, and fixes relative links throughout. No code changes except docstring path corrections in csv_export.py and test_loudness_r128.py. All newly-documented files verified to exist on disk; no stale references to the old paths found outside docs/history/.
Findings
None.
Test results
No tests run — zero executable code changed. The PR's own test plan (lint + unittest discover smoke) is the right call before merge.
Phase boundary check
Clean. Docs only; no Phase 1/2/3 boundary crossings.
Generated by Claude Code
slittycode
left a comment
slittycode
left a comment
There was a problem hiding this comment.
Verdict: APPROVE
Summary
Docs-only sweep: two completed review docs archived into docs/history/, all their cross-references updated to the new depth (../ → ../../), and every living doc (CLAUDE.md, ARCHITECTURE.md, AGENTS.md×2, README.md×2, BACKLOG.md, the ADR, csv_export.py docstring, test_loudness_r128.py docstring) brought in sync with the modules that shipped since the last doc refresh. CI is green on both Frontend and Backend. No code changes.
Findings
No blocking or should-fix findings.
Worth considering (minor accuracy nits in archived files, not worth a follow-up commit):
docs/history/track1-spike-outcome-2026-05-13.mdstill reads "Result (pending CI)" — predates the fix shipping. Archived context, low stakes.- The "Definition of done" checklist inside the archived
external-repo-review-2026-05-13.mdstill has unchecked boxes (e.g.,[ ] Side-by-side endpoint comparison committed). The archive note says all three tracks resolved, so a reader has to reconcile that themselves.
Test results
Frontend: pass. Backend: pass. No test-impacting changes — only docstring edits in csv_export.py and test_loudness_r128.py.
Phase boundary check
Clean. No changes to Phase 1, 2, or 3 logic. No schema changes. No field additions, removals, or renames.
Generated by Claude Code
2 participants
Summary
Documentation had drifted in several places vs. the code. This sweep brings the living docs back in sync and archives one-shot review docs whose action items have all shipped.
Stale-in-place fixes
BACKLOG.md— audition samples moved from "In Progress (branchclaude/gemini-sample-generation-U753E)" to "Shipped". That branch is gone; the feature landed in feat(samples): Phase 3 audition — heuristic WAV/MIDI from Phase 1 + PyTheory #45 and test(samples): end-to-end audio-content assertions for audition output #46.docs/SAMPLE_GENERATION.md— header changes from "Status: Prototype on branch X" to "Status: Shipped".apps/ui/README.md— dropsGoogle Gen AI SDKfrom the Tech Stack. The@google/genaidependency was removed frompackage.json; Gemini is fully backend-mediated.apps/backend/ARCHITECTURE.md— Components table extended to covercsv_export.py,dsp_utils.py,dsp_bandbank.py,sample_*.py,server_samples.py,stage_status.py,symbolic_extract.py,url_ingest.py,phase1_evaluation.py,phase1_report_html.py,utils/cleanup.py. Routes list gains/interrupt,/samples(POST + GET).apps/backend/README.md— canonical-routes list rounded out withDELETE /runs,/interrupt,/source-audio,/export/csv,/spectral-enhancements,/pitch-note-translations,/interpretations,/samples.apps/backend/AGENTS.md— File Map refreshed with the same new modules. New "Operator and Research Scripts" section documentsscripts/(bootstrap, evaluate_*, genre_check, etc.). Stale2026-03-10date stamp bumped.apps/ui/AGENTS.md— File Map expanded withanalysisRunsClient,phase2Validator,mixDoctor,spectralArtifactsClient,sampleGenerationClient,fieldAnalytics,midi/,sessionMusician/, and thetypes/barrel. Notes that the UI no longer imports an AI SDK.CLAUDE.md— backend "Core files" list expanded to match; audition-samples surface called out explicitly.Archived (moved to
docs/history/)external-repo-review-2026-05-13.md— Tracks 1, 2, 3 all shipped or deferred. Archive-note header summarizes the PRs that closed each track.track1-spike-outcome-2026-05-13.md— verification spike concluded; sample-rate fix shipped; regression test lives inapps/backend/tests/test_loudness_r128.py.Cross-references updated
docs/adr/0001-phase1-json-schema-v1.mdapps/backend/csv_export.py(module docstring)apps/backend/tests/test_loudness_r128.py(module docstring)docs/history/README.mdindexTest plan
git grepconfirms no remaining references todocs/external-repo-review-2026-05-13.mdordocs/track1-spike-outcome-2026-05-13.mdoutsidedocs/history/.../to../../to remain navigable from the new depth.npm run lint+unittest discoversmoke run before merge to confirm the docstring edits didn't trip anything.https://claude.ai/code/session_01YNsCxdcxQiTieUNvAgKMd9
Generated by Claude Code